/**
 * 配置 `fromSphere` 方法。
 */
export interface SphereOptions {
  /**
   * 是否创建一个中空的球体。
   * @default false
   */
  isHollow?: boolean;
  /**
   * 当 `isHollow` 为 `true` 时，定义球壳的厚度。
   * @default 1
   */
  thickness?: number;
}

/**
 * 配置 `fromCylinder` 方法。
 */
export interface CylinderOptions {
  /**
   * 是否创建一个中空的圆柱体。
   * @default false
   */
  isHollow?: boolean;
  /**
   * 当 `isHollow` 为 `true` 时，定义圆柱壁的厚度。
   * @default 1
   */
  thickness?: number;
}

/**
 * 配置 `fromPyramid` 方法。
 */
export interface PyramidOptions {
  /**
   * 是否创建一个中空的金字塔。
   * 如果为`true`，将只生成金字塔的表面。
   * @default false
   */
  isHollow?: boolean;
}

/**
 * 配置 `fromCuboid` 方法。
 */
export interface CuboidOptions {
  /**
   * 是否创建一个中空的长方体。
   * @default false
   */
  isHollow?: boolean;
  /**
   * 当 `isHollow` 为 `true` 时，定义长方体壁的厚度。
   * @default 1
   */
  thickness?: number;
}

/**
 * 配置 `fromPath` 方法如何生成路径上的对象。
 */
export interface FromPathOptions {
  /**
   * 是否使用 Catmull-Rom 样条曲线来平滑路径。
   * 如果为 `true`，将会在给定的路径点之间生成一条平滑的曲线。
   * @default false
   */
  useBezier?: boolean;
  /**
   * 当 `useBezier` 为 `true` 时，用于插值的样本点数量。
   * 数量越多，曲线越平滑，但计算成本也越高。
   * @default 20
   */
  bezierSampleCount?: number;
  /**
   * 沿路径放置图章的步长（间隔）。
   * 例如，`step: 5` 表示每隔5个方块的距离放置一个图章。
   * @default 1
   */
  step?: number;
  /**
   * 图章是否应根据路径的切线方向自动旋转对齐。
   * 对于墙体这类需要连续性的结构，应设为 `true`。对于灯柱这类独立物体，可以设为 `false`。
   * @default true
   */
  alignToPath?: boolean;
}

/**
 * 配置 `fromPathWall` 方法。
 * 这是 `FromPathOptions` 的一个子集，专注于墙体生成。
 */
export interface FromPathWallOptions {
  /**
   * 是否使用 Catmull-Rom 样条曲线来平滑墙的路径。
   * @default false
   */
  useBezier?: boolean;
  /**
   * 当 `useBezier` 为 `true` 时，用于插值的样本点数量。
   * @default 20
   */
  bezierSampleCount?: number;
  /**
   * @deprecated 在 `fromPathWall` 中此参数无效，墙体总是连续的。
   */
  step?: number;
}

/**
 * 配置 `fromCone` 方法。
 */
export interface ConeOptions {
  /**
   * 是否创建一个中空的圆锥。
   * @default false
   */
  isHollow?: boolean;
  /**
   * 当 `isHollow` 为 `true` 时，定义锥壁的厚度。
   * @default 1
   */
  thickness?: number;
}

/**
 * 配置 `fromPrism` 方法。
 */
export interface PrismOptions {
  /**
   * 是否创建一个中空的棱柱。
   * @default false
   */
  isHollow?: boolean;
  /**
   * 当 `isHollow` 为 `true` 时，定义棱柱壁的厚度。
   * @default 1
   */
  thickness?: number;
}

/**
 * 配置 `smooth` 方法的元胞自动机算法。
 */
export interface SmoothOptions {
  /**
   * 算法的迭代次数。次数越多，平滑效果越明显。
   * @default 1
   */
  iterations?: number;
  /**
   * 一个空单元格（空气）周围需要有多少个实心邻居方块才能“诞生”一个新的方块。
   * @default 5
   */
  birthThreshold?: number;
  /**
   * 一个实心方块周围需要有多少个实心邻居方块才能“存活”到下一次迭代。
   * 少于此数量的方块将被移除。
   * @default 4
   */
  survivalThreshold?: number;
}

/**
 * 配置 `sharpen` 方法。
 */
export interface SharpenOptions {
  /**
   * 在蓝图顶部随机散播新方块的密度。
   * 值为 0 到 1 之间。
   * @default 0.5
   */
  density?: number;
  /**
   * 锐化效果的最大高度。
   * @default 10
   */
  maxHeight?: number;
}

/**
 * 配置 `cloneToSurface` 方法。
 */
export interface CloneToSurfaceOptions {
  /**
   * 在表面上放置图章的密度。
   * 值为 0 到 1 之间，1 表示在所有可能的表面位置都放置。
   * @default 0.1
   */
  density?: number;
  /**
   * 图章是否应根据其所处表面的法线方向对齐。
   * 例如，在斜坡上的树会直立生长（false），而苔藓会贴着斜坡（true）。
   * @default false
   */
  alignToSurface?: boolean;
  /**
   * 是否对每个图章应用随机的Y轴旋转。
   * @default false
   */
  randomYRotation?: boolean;
  /**
   * 一个法线向量数组，限制了只在具有这些法线的表面上放置图章。
   * 例如 `[new GameVector3(0, 1, 0)]` 表示只在朝上的水平表面放置。
   * @default undefined (允许所有表面)
   */
  allowedSurfaceNormals?: GameVector3[];
}

/**
 * 定义了 `replaceByPattern` 方法中使用的单个替换目标。
 */
export type PatternEntry = {
  /** 新方块的ID。 */
  id: voxelId;
  /** 新方块的旋转方向。如果未定义，则保留原方块的旋转。 */
  rot?: voxelRotation;
  /** 此方块在替换中被选中的权重。权重值越大，被选中的几率越高。 */
  weight: number;
};

/**
 * 定义了 `replaceByPattern` 的替换规则。
 * 这是一个Map，键是要被替换的方块ID，值是一个 `PatternEntry` 数组。
 * @example
 * new Map([
 *   [1, [ // 当遇到方块ID为 1 (stone) 时
 *     { id: 1, weight: 80 }, // 80% 几率保持为 stone
 *     { id: 4, weight: 15 }, // 15% 几率变为 cobblestone
 *     { id: 5, weight: 5 }   // 5% 几率变为 andesite
 *   ]]
 * ])
 */
export type PatternMap = Map<voxelId, PatternEntry[]>;
